CLI describe, docs and conformance run (Stage 1, PR 17) - #220

What

• New command morphobricks-preprocessing describe EXPERIMENT [--output FOLDER] [--exclude PATH] [--publish] (cli_describe.py, wired in cli.py). It prints the draft experiment description in plain language: proposed IDs (none, never repaired, for a folder that cannot be an ID), repeats with folders and image counts, references, migration notes, and every open question with what the user has to do. It only calls existing functions (discover_experiment, draft_from_discovery, migrate_legacy_design, load_description, reconcile); no rule is added.
• Against a published morphobricks.toml it compares the folders with it (new, gone, image counts, repeats to confirm again). Folder structure only: no header is read, so channels are not compared (it says so).
• Writes nothing, takes no lock, reads no image, confirms nothing (owner rule).
• --publish refuses (exit 1, Not published. What is missing: plus every item) unless nothing is open; "Nothing to publish" (exit 0) for a published description matching the folders. Errors exit 1, as in the other commands.
• Docs: contract §12 and §16, user guide "Describe your experiment", plan §12 question 77 (owner answers Q1 to Q8), README, CHANGELOG, docs/conformance.md.

Why

Stage 1 design row 17: CLI users need to see and publish the description without the notebook.

Regression evidence

tests/test_cli_describe.py (11 tests). On origin/main code (new source stashed): 11 failed (invalid choice: 'describe'). With the change: 11 passed.

Checks

python tools/check.py: Ruff and format clean; pytest 4324 passed, 4 skipped, 0 failed; check.py --rules passes (no baseline grew, files under 600 lines).

Conformance result

Base 68b2a4b, 8 Nov 2026: whole suite 4324 passed, 4 skipped; Spec modules 1535 passed, 0 skipped. The 4 skips are outside the Spec modules (3 case-insensitive-name tests, 1 file-mode test run as root) and are not counted as passes. Recorded in docs/conformance.md, which also lists what the run does not cover.

Needs an owner decision

1. --publish cannot complete a draft. The design assumes a saved draft (morphobricks.draft.json) holding the user's answers, plus a Draft to Description step (channels, image types, masks). Neither exists on main (the Draft is in memory, every ID slot is pending, there is no builder). Inventing the file format here would be guessing, so --publish always lists what is missing for a draft of folders. Decide the draft file format and the owner of that step (notebook PRs 14-16?) before --publish can publish.
2. Publishing an image-count-only change needs the image_count_changed record (open PR Publication writes the removed and image_count_changed records (RR2, RR1) #216); --publish lists such a change as not publishable here.
3. Owner questions Q1-Q8 are recorded from the coordinator's notes (all recommendations accepted); please check the wording of plan question 77.
4. Spec golden CSVs and PRs 13-16 items are not in this conformance run, so it is not a release sign-off.

Will conflict on CHANGELOG/docs with #212 #213 #215-#218; keep both sides.

Generated by Claude Code